home *** CD-ROM | disk | FTP | other *** search
/ Skunkware 5 / Skunkware 5.iso / src / X11 / willow-2.3 / README next >
Text File  |  1995-07-08  |  15KB  |  313 lines
  1. /***********************************************************************
  2.  *                                                                     *
  3.  *              WILLOW(tm) Information Retrieval Software              *
  4.  *     (Washington Information Looker-upper Layered Over Windows)      *
  5.  *             Copyright 1992-1994 University of Washington            *
  6.  *                                                                     *
  7.  *   Willow is a trademark of the University of Washington.  No        *
  8.  *   commercial use of this trademark or software may be made without  *
  9.  *   prior written permission of the University of Washington.         *
  10.  *                                                                     *
  11.  * Permission to use, copy, modify, and distribute Willow(tm) software *
  12.  * and its documentation for any noncommercial purpose is hereby       *
  13.  * granted, provided that the above copyright notice appears in all    *
  14.  * copies and that both the above copyright notice and this permission *
  15.  * notice appear in supporting documentation, and that the name of the *
  16.  * University of Washington not be used in advertising or publicity    *
  17.  * pertaining to distribution of the software without specific,        *
  18.  * written prior permission.  This software is made available "as is", *
  19.  * and THE UNIVERSITY OF WASHINGTON DISCLAIMS ALL WARRANTIES, EXPRESS  *
  20.  * OR IMPLIED, WITH REGARD TO THIS SOFTWARE, INCLUDING WITHOUT         *
  21.  * LIMITATION ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS    *
  22.  * FOR A PARTICULAR PURPOSE, AND IN NO EVENT SHALL THE UNIVERSITY OF   *
  23.  * WASHINGTON BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL     *
  24.  * DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA  *
  25.  * OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, TORT (INCLUDING       *
  26.  * NEGLIGENCE) OR STRICT LIABILITY, ARISING OUT OF OR IN CONNECTION    *
  27.  * WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.                       *
  28.  *                                                                     *
  29.  * For further information please contact:                             *
  30.  * Willow Project                                                      *
  31.  * Information Systems                                                 *
  32.  * University of Washington                                            *
  33.  * 4545 15th NE, 1st floor                                             *
  34.  * Seattle, Washington, 98105, USA                                     *
  35.  * Internet: willow@cac.washington.edu                                 *
  36.  ***********************************************************************/
  37.  
  38.                          September 6, 1994
  39.  
  40.           Building and Installing Willow Source Code
  41.  
  42. This file contains instructions for how to build and install the
  43. Willow source code distribution, and a description of the included
  44. files.
  45.  
  46. Note that there are pre-compiled Willow binaries available for a
  47. variety of platforms. If binaries for your platform exist, we
  48. recommend that you use them rather than try to compile yourself.
  49. Currently available are binaries for DEC/Ultrix, IBM/RS6000-AIX,
  50. Sun/Solaris, and Sun/SunOS.
  51.  
  52.      ##########################################################
  53.      #           Send your questions and comments to:         #
  54.      #                willow@cac.washington.edu               #
  55.      # Or, if you wish to share them with other willow users: #
  56.      #             willow-info@cac.washington.edu             #
  57.      ##########################################################
  58.  
  59.  
  60. Building Willow
  61. ===============
  62. 0. Executive summary of the next 12 steps:
  63.       Get and unpack the distribution
  64.       Edit the file "Config"
  65.       imake  /* with no arguments! */
  66.       make world
  67.       make install
  68.  
  69. 1. If you have not done so already, the first step is to join one of
  70.    the two Willow mailing lists, so that you can be informed of new
  71.    releases of Willow. It is crucial that you install new versions in
  72.    a timely manner, because old versions are sometimes unable to
  73.    connect to the host databases.
  74.  
  75.    To join the "willow-info" public mailing list for Willow release
  76.    announcements and general Willow discussion, send a request to:
  77.       willow-info-request@cac.washington.edu
  78.  
  79.    If you want to receive release announcements only, you can join the
  80.    "willow-announce" list by sending a request to:
  81.       willow-announce-request@cac.washington.edu
  82.  
  83. 2. Next, you must ftp the Willow source distribution from
  84.    ftp.cac.washington.edu, in the willow directory. There are
  85.    different versions of the Willow distribution for different types
  86.    of user -- University of Washington, NorthWestNet, and everybody
  87.    else. Go to the appropriate sub-directory for your class -- uw,
  88.    nwnet, or public, and get willow.src.tar.Z (be sure to transfer in
  89.    binary mode).
  90.  
  91. 3. Uncompress the file. Just execute the command 
  92.       uncompress  willow.src.tar.Z
  93.    and the file will be replaced by willow.src.tar.  
  94.  
  95. 4. Un-tar the file. Execute the command
  96.       tar xvf willow.src.tar
  97.    and a directory called willow will be created, with all the
  98.    necessary files underneath it. 
  99.  
  100. 5. Hopefully, everything you need to modify in order to successfully
  101.    build Willow and its drivers is isolated into the file Config. Open
  102.    that file in your favorite editor, and follow the instructions
  103.    there to configure it for your particular site.
  104.  
  105. 6. From the willow directory, type the command "imake" with no
  106.    arguments (if you do not have imake on your system, get it). The
  107.    Willow distribution does not use the X11 config files, so do not
  108.    use xmkmf. There should now be a file called "Makefile" in the
  109.    willow directory. If you find you need to go back and modify the
  110.    Config file again, be sure to use imake to regenerate your Makefile
  111.    afterwards.
  112.  
  113. 7. Type the command "make world". This will first execute the
  114.    "Makefiles" target to create Makefiles in each of the source
  115.    sub-directories, then the "programs" target to run the Makefiles
  116.    and build the programs. So far, Willow has been successfully built
  117.    on DEC/Ultrix, IBM RS6000, Sun/Solaris, SunOS, 386/BSD, DEC/vax
  118.    (BSD 4.3), and HP/UX. Feel free to contact us if you have problems
  119.    building. And we encourage you to send us back any fixes you come
  120.    up with for future releases.  Once everything is built, if you wish
  121.    to run Willow from the source directory you must be sure to set the
  122.    "Willow*willowDir" resource as described in the file
  123.    doc/Customization. Creating a temporary link from /usr/lib/X11/willow
  124.    to your source directory will also work.
  125.  
  126. 8. Install willow in its final resting place by typing "make install".
  127.    Note that unless you own the installation, binary, and man-page
  128.    directories as described in Config, this step will require you to
  129.    become root in order to run.
  130.  
  131.    You may want to do a "make -n install" to preview what "make install"
  132.    will do. Basically it is the following steps...
  133.      If there is already an installed willow.old directory, remove it.
  134.      If there is already an installed willow directory, move it to
  135.        willow.old. 
  136.      Create the installation directory (usually /usr/local/willow).
  137.      If /usr/lib/X11/willow already exists as symbolic link, remove it. 
  138.      If your installation directory is anything than other than
  139.        /usr/lib/X11/willow, create a symbolic link from
  140.        /usr/lib/X11/willow to your installation directory.
  141.      Copy the necessary files to your installation directory.
  142.      If there already is a link called willow in your binary
  143.        directory, remove it.
  144.      Create a symbolic link called willow in your binary directory to
  145.        the willow executable in your installation directory.
  146.      Copy doc/willow.man to willow.1 in your manual page directory.
  147.  
  148.    If you are a file-system purist, and do not even want a symbolic
  149.    link in /usr/lib/X11, you can remove the /usr/lib/X11/willow link,
  150.    but then you will have to use resources to change the default
  151.    Willow directory. See doc/Customization for more information.
  152.  
  153. 9. Make sure that you have the Free Software Foundation's "gunzip"
  154.    decompression program available on your system. The help bitmap
  155.    files are stored in gzipped format, and gunzip is required for
  156.    Willow to read them. If you do not have it, the gzip package is
  157.    available via ftp from prep.ai.mit.edu in pub/gnu. Note that Willow
  158.    will run fine without gunzip until you press a Help button, so you
  159.    can save this step for later.
  160.  
  161.    By default, Willow will create an external gunzip process each time
  162.    a help screen is viewed. If you find that this extra CPU usage is a
  163.    problem on your system (this is only likely if you have a large
  164.    number of simultaneous Willow users on the same CPU) then you may
  165.    want to spend the extra disk-space and pre-expand all of the help
  166.    bitmap files. Bitmap files are in the subdirectories of
  167.    willow/help, and the file names are of the form "screen#.gz".  The
  168.    following command line, when run from the willow directory, can be
  169.    used to expand all of the help bitmaps which are currently
  170.    compressed: 
  171.         find help -name "*.gz" -print | xargs gunzip
  172.  
  173.    Similarly, this command line can be used to re-compress any bitmaps
  174.    that have been expanded:
  175.         find help -name "screen*" -print | grep -v ".gz" | xargs gzip
  176.  
  177. 10.Set up any customized Willow resources you are interested in.
  178.    Willow will run just fine with its fallback resource values, so
  179.    this step is purely optional. The resources a system administrator
  180.    are likely to be interested in are described in doc/Customization.
  181.    If you do want system-wide resources customized, you can create a
  182.    file /usr/lib/X11/app-defaults/Willow and list those resources.
  183.  
  184.    Note that Willow depends on certain colors that are only defined in
  185.    Release 4 and newer version of X, so if you still have the R3 color
  186.    database installed, you should update it (/usr/lib/X11/rgb.*).
  187.  
  188.    Also note that Willow expects to find the standard X11R4 75dpi font
  189.    set available. Even if you are on a 100dpi or higher screen, you
  190.    should be sure to have the 75dpi fonts on your font path. That way,
  191.    Willow will be guaranteed to have the correct appearance. However
  192.    if you are on a high-res (1280x1024 or more pixels) screen, you
  193.    probably want to run Willow in extra-large mode, to take advantage
  194.    of your extra screen real estate. See the file willow.X for more
  195.    information on setting the Willow*size resource.
  196.  
  197. 11.Note that all applications built with Motif 1.1 and higher require
  198.    the presence of the file /usr/lib/X11/XKeysymDB. If when you start
  199.    Willow you see error messages such as 
  200.       "translation table syntax error: Unknown keysym..."
  201.    
  202.    You should install that file. There is a copy available for ftp in
  203.    the pub/willow directory on ftp.cac.washington.edu.
  204.  
  205. 12.Platform-specific peculiarities
  206.    Sun/Solaris:
  207.      The version of telnet currently supplied with Solaris does not
  208.      work properly with Willow's uwbrs driver. A patched telnet is
  209.      available from Sun. Contact Sun support (generally that means
  210.      calling 1-800-USA-4SUN) and ask for patch 101681-01.
  211.  
  212.      Due to what we think is a bug in the solaris popen() function,
  213.      on-the-fly gunzipping of help screens as described above, fails
  214.      on versions of Solaris earlier than 2.3. In this case you will
  215.      have to pre-gunzip all of the files.
  216.  
  217.  
  218. File Contents
  219. =============
  220. The following files are included in the Willow source code
  221. distribution...
  222.  
  223. Config
  224.    As described above, this is the imake configuration file you must
  225.    edit before you can build Willow on your machine.
  226.  
  227. Imake.tmpl
  228.    The basic template file needed by imake. You can ignore it.
  229.  
  230. Imakefile
  231.    The model which imake uses to generate Makefiles. You can ignore it.
  232.  
  233. README
  234.    You are reading it right now!
  235.  
  236. db.conf
  237.    The database configuration file. This file tells Willow what
  238.    databases should be listed in the Database menu, and exactly how to
  239.    present this database to the user. See doc/Customization and the
  240.    db.conf file itself, for more information.
  241.  
  242. doc
  243.    This is a directory which contains supplemental documentation,
  244.    including: 
  245.  
  246.    CHANGES 
  247.       Summary of the changes for the current version, along with all
  248.       changes since version 2.0.
  249.  
  250.    COPYRIGHT
  251.       A statement of the University of Washington copyright, along
  252.       with statements from all other institutions which have
  253.       contributed code.
  254.  
  255.    Customization
  256.       A guide to customizing Willow for your site, including available
  257.       system-wide resources and a description of how to add new
  258.       databases. 
  259.  
  260.    Tech-Report.ps
  261.       This postscript file is a write-up up of the Willow
  262.       architecture. It might make interesting background reading for
  263.       more technical users, but it is not required. Note that an
  264.       on-line hypertext version of this document is available via
  265.       Mosaic or any other www browser, at the URL:
  266.         http://www.cac.washington.edu/willow
  267.  
  268.    willow.man
  269.       A manual page for willow.
  270.  
  271.    willow.X
  272.       This is the X resource template file for Willow. It shows all
  273.       the resources that a user might want to set.
  274.  
  275.    Z39.50_Supplement
  276.       Contains various supplemental information about using Willow's
  277.       Z39.50 driver. Z39.50 is a standard ANSI protocol for
  278.       information search and retrieval.
  279.  
  280. drivers
  281.    This directory contains the database-driver programs for all the
  282.    databases that Willow knows how to speak to. The driver is a
  283.    program that translates between Willow and a particular database
  284.    system. For more information, read Tech-Report.ps. 
  285.  
  286. help
  287.    This is the directory where the text and bitmap files accessed by
  288.    the online help system live by default.
  289.  
  290. src
  291.    This directory contains subdirectories with the actual Willow
  292.    source code, and source code for the UW-BRS database driver and
  293.    MIT's Z39.50 database driver. See Tech-Report.ps for an explanation
  294.    of exactly what a database driver is.
  295.  
  296. tools
  297.    This directory contains miscellaneous programs you might find
  298.    useful in conjunction with Willow. Nothing here is strictly
  299.    necessary for getting Willow to run.
  300.  
  301. uid
  302.    This directory contains binary files which describe portions of the
  303.    willow user interface. They are created with the motif UIL
  304.    compiler. This directory is empty until you actually build Willow.
  305.  
  306. willow
  307.    This is the Willow program itself. Of course this file does not
  308.    exist until you build it.
  309.  
  310. xbm
  311.    This directory contains all of the bitmap files that Willow needs
  312.    at run-time.
  313.